Welcome to SAVEMAIL Macro v2.42
------------------
To be used with Macro5 (from v2.37) and:
- a Psion S5 or Geofox + MsgSuite Email (v1.52)
- a Psion S5mx & mx-pro + the built-in Email program

WHAT'S NEW
------------------
v 2.42 * for 5mx users only: now the macro lets you specify a Date and Time
         which will be put in the Time field of any stored message
       * for 5mx users only: the "auto-delete" option has been re-enabled, as
         the above option allows you a better handling of each message

PLEASE READ CAREFULLY
------------------
SaveMail is a macro that automates the process of copying your messages
from Psion Email (both MsgSuite and the Epoc R5 built-in Email app) to
any number of  "preformatted" Psion Data files (e.g. one for Work and
another for Home), or to a "plain" Psion Word documents, where they can
be easily edited, sorted, printed, searched or simply stored.
Before proceeding, keep in mind the following:
* especially when you choose to store multiple messages, SaveMail
  may take some time to accomplish its task: please note that while the
  macro is running, Macro5 is NOT available for other operations and you
  also should NOT switch to other tasks or applications;
* be also advised NOT to touch the keyboard while SaveMail is running,
  because you could interfere with the scheduled sequence of keystrokes,
  thus leading to some misbehavior of the macro itself (including the
  deletion of all your messages in the worst case, only if the "auto-delete"
  option is selected);
* if a message contains one or more ATTACHMENTS, the macro simply
  ignores them, so be careful to manually save them before deleting the
  original message from MsgSuite;
* use the "auto-dele" option with care, as there is no way of restoring
  any deleted message from Psion Email. I strongly recommend a good
  BACKUP before starting to play with SaveMail...
* I decline any responsibility for any loss of data that may result from
  the use of this program.

HOW TO INSTALL AND USE
------------------
1)  Unzip the savemail.zip file.
2)  Copy SaveMail.opo, SaveMail.ico  and SaveMail.box to the folder
    where you keep all the macros of Macro5. The SaveMail.box file is
    the "preformatted" Data file used to create new MailBox Data files
    from within the macro. DO NOT use this file to store your messages,
    just leave it empty in your macros folder.
3)  Launch Macro5 and create a new shortcut to SaveMail.opo (remember
    to select "Macro" and not "Program" in the shortcut "Type" definition).
4)  Call SaveMail macro through the associated Macro5 shortcut: the first
    time you launch it, a Setup process will start, showing your System
    settings: location of your Email program, YES button keystroke, Date
    format and Macro5 version (remember you need v2.37 at least, as this
    macro is not tested with previous releases; also note that if you upgrade
    from v2.37 to 2.40 or later in a second time, you will have to relaunch
    this setup): simply check if these settings are correct; if SaveMail fails
    to detect the right "Yes button keystroke" of your Email app (needed to
    confirm the deletion of the original messages if the "auto-delete" option
    is selected), you can change this by selecting the 'Change YES' button
    (it may happen if the language of your S5 differs from the one of Email);
    once passed the first window, a second one will ask you for the location
    of your default Data file (the one that will be used by default to store
    your messages); if you do not have previous .box Data files to use,
    select NEW and a dialog will let you create a new Data file and place
    it wherever you want (the .box extension will be automatically added
    if you forget it); finally a last window will ask if you want to enable
    the choice of different Data files (note that you can create multiple
    Data files also in a second time using the NEW option), and  if you
    want to open a dialog window to automate the process of storing
    (and deleting) a group of messages each time you launch SaveMail.
5)  All these settings are stored in a SaveMail.ini file located in the
    "C:\System\" folder; if for any reason you need to change these settings
    (e.g. you changed the date format in the System settings, or upgraded
    Macro5 from v2.37 to v2.40), simply delete the file, and when you will
    recall SaveMail, the setup process will be launched again.
    Alternatively, you can relaunch the Setup procedure from within the
    macro, in the target data file window (if enabled).
6)  Once accomplished the setup process, these are the steps to follow:
    - launch your Email program
    - select the Inbox or the Sent folder
    - highlight a message without opening it (do not press Enter)
    - call SaveMail macro through the associated Macro5 shortcut
7)  According to the options you have selected in the setup process, once
    launched, SaveMail may:
    - ask for the location of your target Data file to store your message(s)
    - ask for the number of messages to automatically store
    - ask if it has to delete the original message(s) from Email
    - ask if the highlighted message has no subject (see known issues)
8)  If everything is OK, once SaveMail has finished its task, you should
    find yourself again in the Email screen, but you should also find the
    message(s) stored in the (selected) target Data file.

UPGRADING
------------------
* If you have v2.10 or later, simply replace SaveMail.opo and SaveMail.box
  with the new ones (all your settings won't be lost).
* If you already have a MailBox Data file from v2.00, simply rename it,
  in order to add the ".box" extension.
* If you need to upgrade from v1.xx just follow the instructions in the
  history.txt file.

NOTES ON THE "PREFORMATTED" MAILBOX DATA FILES
------------------
The "preformatted" DATA files, where the messages from Email are
stored, have the following labels:
Subject  (type: text length: 250)  second sorting key (ascending)
Date     (type: text length: 30)   first sorting key  (descending)
From     (type: text length: 250)
To       (type: text length: 250)
CC/BCC   (type: memo length: unlimited)
Body     (type: memo length: unlimited)

NOTES ON THE  "PLAIN" WORD FILE
------------------
You can save your message(s) to a "plain" Psion Word file; the macro
can create a new Word target file for you (adding a .wbox extension to the
name), or can use an existing one (only with the .wbox extension); each
field of the original message(s) is copied as text, with an appropriate
description (e.g. subject, date etc.); if the target file already contains other
messages, the new one will not overwrite them, but will be placed at the
beginning of the document.

NOTES ON THE DATE FORMAT OF THE  MESSAGES
------------------
This macro copies the DATE string of the original message (no matter
which format is selected in your System settings) and changes it to
"yyyy/mm/dd hh:mm:ss" in order to have them correctly sorted by date
in the MailBox file (it works both with 12h and 24h TIME format).

TRANSLATING THE OPL CODE
------------------
Feel free to modify the source code (SaveMail.opl) as you like...
If the translation fails with a "not found" message and the cursor at the
line INCLUDE "Systinfo.oxh", it means that you have to install that file
to your "System\OPL\" folder; feel free to email me at the address below
and I will send you a copy.

KNOWN ISSUES
------------------
For S5 and Geofox owners:
* If a message has the TO, CC or BCC fields particularly long (e.g. sent
  to a list of people) only the first 250 characters will be copied to the Data
  file; if this happens, a dialog is displayed to alert you
* If a message has NO SUBJECT, you have to tell this to SaveMail, using
  the apposite DIALOG WINDOW (if enabled), otherwise the macro will put
  the content of the first field it finds above the empty subject into the
  subject of the MailBox file and you have to manually rearrange the fields
  once the macro has ended its task...
For S5mx owners:
* CC/BCC fields, if present, are ignored and must be manually copied
* can't find how to have access to the date field of a message, so
  the date field in the target data file refers to the time of storing
  or the time you can specify in the appropriate dialog window

ACKNOWLEDGMENTS
------------------
A great thank you to:
* Pascal Nicolas for writing Macro5 and helping me in making this macro
  work... Visit his homepage for a huge library of useful macros:
  http://pnicolas.epocboulevard.com/
* Mario Collado (author of Assistant) for all his suggestions!
  Visit his homepage at http://www.psionwelt.net/MarioCollado/

Any comments & suggestions are welcome!

E-mail me at:
  sergioalisi@geocities.com
Visit my homepage at:
  http://www.geocities.com/siliconvalley/bridge/1492

THANKS & ENJOY